home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacOS 8 Resources / Developer Tools / Mac OS 8 Interfaces & Libraries / Interfaces / IDLIncludes / OCE.idl < prev    next >
Text File  |  1996-05-01  |  27KB  |  677 lines
  1. /*
  2.      File:        OCE.idl
  3.  
  4.      Contains:    Apple Open Collaboration Environment (AOCE) Interfaces.
  5.  
  6.      Version:    Technology:    AOCE Toolbox 1.02
  7.                  Release:    Universal Interfaces 3.0d3 on Copland DR1
  8.  
  9.      Copyright:    © 1984-1996 by Apple Computer, Inc.  All rights reserved.
  10.  
  11.      Bugs?:        If you find a problem with this file, send the file and version
  12.                  information (from above) and the problem description to:
  13.  
  14.                      Internet:    apple.bugs@applelink.apple.com
  15.                      AppleLink:    APPLE.BUGS
  16.  
  17. */
  18. #ifndef __OCE_IDL__
  19. #define __OCE_IDL__
  20.  
  21. #include <somobj.idl>
  22. #include <somcls.idl>
  23.  
  24. #ifndef __TYPES_IDL__
  25. #include <Types.idl>
  26. #endif
  27. #ifndef __ALIASES_IDL__
  28. #include <Aliases.idl>
  29. #endif
  30. #ifndef __APPLEEVENTS_IDL__
  31. #include <AppleEvents.idl>
  32. #endif
  33.  
  34. #ifdef __SOMIDL__
  35.  
  36. #if FOR_SYSTEM7_ONLY
  37. /* All utility routines defined here are callable at interrupt level. */
  38. typedef unsigned short            OCERecordTypeIndex;
  39.  
  40. typedef unsigned short            OCEAttributeTypeIndex;
  41.  
  42. /*
  43.  For anyone who absolutely needs a define of the body of the standard record or
  44. attribute type, use these below.  CAUTION!  All the types below are assumed to be
  45. in character set 'smRoman'.  If you try to compare these to some RString or
  46. AttributeType variable, you must take the character set code into account.  Future
  47. standard types may be defined using character sets other than 'smRoman'. 
  48. */
  49. /*
  50.  All these standard definitions begin with the Apple symbol (not shown here).
  51.  
  52. NOTE:  To access these, you must call OCEGetIndRecordType or OCEGetIndAttributeType
  53. with the proper index.  These routines return pointers to the standard type.
  54. This was done so that code fragments (INITs, CDEVs, CSAMs, etc). which cannot
  55. use global data can also use these. 
  56. */
  57. /* Indices for the standard definitions for certain record types (OCERecordTypeIndex): */
  58. /* Indices for the standard definitions for certain attribute types (OCEAttributeTypeIndex): */
  59. #endif
  60. #if FOR_SYSTEM7_ONLY
  61. /* Miscellaneous enums: */
  62. /*
  63.  This enum is used to select the kind of RString in calls such as OCERelRString,
  64. OCEEqualRString, and OCEValidRString.
  65.  
  66. eGenericSensitive and eGenericInsensitive are enumerators that can be used if you
  67. use RStrings for things other than what you see in this file.  If you want them to
  68. be compared in a case- and diacritical-sensitive manner (c != C != Á), use
  69. eGenericSensitive.  If you want them to be compared in a case- and diacritical-
  70. insensitive manner (c = C = Á), use eGenericInensitive.
  71. WARNING:  do not use eGenericSensitive and eGenericInsensitive with catalog
  72. names, entity names, pathname parts, entity types, network specs, or attribute
  73. types!  Don't assume that you know how they should be compared!!! 
  74. */
  75. typedef unsigned short            RStringKind;
  76.  
  77. /* Values for the signature field in Discriminator */
  78. typedef unsigned long            OCEDirectoryKind;
  79.  
  80. /* Values returned by GetDSSpecInfo() */
  81. /* Values for AttributeTag */
  82. /*
  83.  Bit flag corresponding to the canContainRecords bit.  Use it like this:
  84.     if (foo & kCanContainRecords)
  85.         then this dNode can contain records!
  86. kForeignNode is used to indicate nodes in the name hierarchy that correspond to
  87. foreign catalogs (meaning ADAP sees no clusters or DNodes beneath it, but
  88. mail routers might be able to route to clusters beneath it. 
  89. */
  90. /* DirNodeKind */
  91. typedef unsigned long            DirNodeKind;
  92.  
  93. /**** Toolbox Control ****/
  94. /*
  95.  We will have a version number and attributes for toolboxes off the aa5e trap
  96. and the S&F server trap.
  97.  
  98. This includes the OCE toolbox and S&F Server.  [Note: the S&F server will
  99. change to ONLY service ServerGateway calls --it will then be necessary to run
  100. it co-resident with an OCE toolbox].
  101.  
  102. The high order word will represent the S&F Server version number.  The low
  103. order word will represent the OCE toolbox version number.  These will be zero
  104. until the component is up and running.  It is not possible to know these
  105. a-priori. Note: there will not be a seperate version numbers for each component
  106. in the OCE toolbox or S&F server.
  107.  
  108. The above is consistent with the standard System 7.0 usage of Gestalt.
  109.  
  110. The oce tb attribute gestaltOCETBPresent implies the existence of OCE on a
  111. machine.
  112.  
  113. The OCE TB attribute gestaltOCETBAvailable implies the availablity of OCE calls.
  114.  
  115. The attribute gestaltOCESFServerAvailable implies the availablity of OCE calls
  116. available through the S&F server. This are essentially the server gateway calls.
  117.  
  118. Any (future) remaining OCE attributes may not be established correctly until
  119. the attribute gestaltOCETBAvailable is set.
  120.  
  121. The gestalt selectors and values are listed below: 
  122. */
  123. /*
  124.  version includes:
  125.  *  dirtb
  126.  *  authtb
  127.  *  mailtb
  128.  *  ipmtb
  129.  *  personal catalog
  130.  *  ADSPSecure
  131.  * e.g. all interfaces dependent on the aa5e trap. 
  132. */
  133. /*    Constants used for Transitions. */
  134. /* Some definitions for time-related parameters: */
  135. /* Interpreted as UTC seconds since 1/1/1904 */
  136. typedef unsigned long            UTCTime;
  137.  
  138. /* seconds EAST of Greenwich */
  139. typedef long                    UTCOffset;
  140.  
  141. /* This is the same as the ScriptManager script. */
  142. typedef short                    CharacterSet;
  143.  
  144. /**** RString ****/
  145. /*
  146.  struct RString is a maximum-sized structure.  Allocate one of these and it will
  147. hold any valid RString. 
  148. */
  149. typedef SOMLargeStruct            RString;                    /* Derived from a struct of 260 bytes in size */
  150.  
  151. /* struct ProtoRString is a minimum-sized structure.  Use this for a variable-length RString. */
  152. typedef SOMFourByteStruct        ProtoRString;                /* Derived from a struct of 4 bytes in size */
  153.  
  154. typedef OpaquePtr                RStringPtr;                    /* Substituted OpaquePtr for ``RString*'' */
  155.  
  156. typedef OpaquePtr                RStringHandle;                /* Substituted OpaquePtr for ``RStringPtr*'' */
  157.  
  158. typedef OpaquePtr                ProtoRStringPtr;            /* Substituted OpaquePtr for ``ProtoRString*'' */
  159.  
  160. typedef SOMLargeStruct            RString64;                    /* Derived from a struct of 68 bytes in size */
  161.  
  162. typedef SOMLargeStruct            RString32;                    /* Derived from a struct of 36 bytes in size */
  163.  
  164. /*
  165.  Standard definitions for the entity type field and attribute type
  166. have been moved to the end of the file. 
  167. */
  168. /*
  169.  Copies str1 to str2.  str2Length is the size of str2, excluding header.
  170. A memFull error will be returned if that is not as large as str1->dataLength. 
  171. */
  172. /*
  173.     Make an RString from a C string.  If the c string is bigger than rStrLength,
  174. only rStrLength bytes will be copied. (rStrLength does not include the header size) 
  175. */
  176. /*
  177.     Make an RString from a Pascal string.  If the Pascal string is bigger than rStrLength,
  178. only rStrLength bytes will be copied. (rStrLength does not include the header size) 
  179. */
  180. /*
  181.     Make a Pascal string from an RString.  It's up to you to check the char set of
  182. the RString, or if the length of the RString is greater than 255 (the Pascal string's
  183. length will simply be the lower byte of the RString's length).  The StringPtr that is
  184. returned will point directly into the RString (no memory will be allocated). 
  185. */
  186. /*
  187.     Check the relative equality of two RStrings.  Determines if str1 is greater than,
  188. equal to, or less than str2.  Result types for OCERelRString are defined in <OSUtils.h>
  189. (same as for RelString). 
  190. */
  191. /*    Check for equality of two RStrings. Returns true if equal. */
  192. /*    Check the validity of an RString.  Returns true if the RString is valid */
  193. /**** CreationID ****/
  194. typedef SOMLargeStruct            CreationID;                    /* Derived from a struct of 8 bytes in size */
  195.  
  196. typedef CreationID                AttributeCreationID;
  197.  
  198. typedef OpaquePtr                CreationIDPtr;                /* Substituted OpaquePtr for ``CreationID*'' */
  199.  
  200. /* Returns a pointer to a null CreationID . */
  201. /* Returns a pointer to a special CreationID used within the PathFinder. */
  202. /* Sets the CreationID to a null value. */
  203. /* Copies the value of cid1 to cid2. */
  204. /* Check the equality of two CreationIDs. */
  205. /**** NetworkSpec ****/
  206. /*
  207.  For the record, a NetworkSpec is an RString with a smaller maximum size.
  208. I don't just typedef it to an RString, because I want the definition of the NetworkSpec
  209. struct to contain the max length.  But it should be possible to typecast any
  210. NetworkSpec to an RString and use all the RString utilities on it. 
  211. */
  212. typedef SOMLargeStruct            NetworkSpec;                /* Derived from a struct of 36 bytes in size */
  213.  
  214. typedef OpaquePtr                NetworkSpecPtr;                /* Substituted OpaquePtr for ``NetworkSpec*'' */
  215.  
  216. /**** PackedPathName ****/
  217. /*
  218.  struct PackedPathName is a maximum-sized structure.  Allocate one of
  219. these and it will hold any valid packed pathname. 
  220. */
  221. typedef SOMLargeStruct            PackedPathName;                /* Derived from a struct of 1024 bytes in size */
  222.  
  223. /*
  224.  struct ProtoPackedPathName is a minimum-sized structure.  Use this
  225. for a variable-length packed PathName. 
  226. */
  227. typedef SOMTwoByteStruct        ProtoPackedPathName;        /* Derived from a struct of 2 bytes in size */
  228.  
  229. typedef OpaquePtr                PackedPathNamePtr;            /* Substituted OpaquePtr for ``PackedPathName*'' */
  230.  
  231. typedef OpaquePtr                ProtoPackedPathNamePtr;        /* Substituted OpaquePtr for ``ProtoPackedPathName*'' */
  232.  
  233. /*
  234. Copy the contents of path1 to path2.  path2Length is the size of path2, and must
  235. be large enough to hold a copy of path1.  A memFull error will be returned if that
  236. is not the case.
  237. */
  238. /*
  239. Returns true if packed path pointer is nil, or is of zero length, or is of
  240. length 2 and nParts of zero.
  241. */
  242. /*
  243. OCEUnpackPathName breaks apart the path into its component RStrings, writing string
  244. pointers into the array 'parts', which the client asserts can hold as many as
  245. 'nParts' elements. The number of parts actually found is returned.  Strings are
  246. placed in the array in order from lowest to highest.  The first pathName element
  247. beneath the root appears last.  NOTE THAT THE UNPACKED STRUCT CONTAINS POINTERS INTO
  248. THE PACKED STRUCT - DON'T DELETE OR REUSE THE PACKED STRUCT UNTIL YOU ARE FINISHED
  249. WITH THE UNPACKED STRUCT AS WELL
  250. */
  251. /*
  252. OCEPackedPathNameSize computes the number of bytes of memory needed to hold a
  253. PackedPathName manufactured from the array of parts.  This length
  254. includes the length of the length field of PackedPathName, so it
  255. is safe to do a NewPtr (OCEPackedPathNameSize(...)).
  256. */
  257. /* OCEDNodeNameCount returns the number of RStrings contained within the path. */
  258. /*
  259. OCEPackPathName packs the parts into the storage provided as 'path'.  path must be
  260. large enough to hold the packed pathname.  A memFull error will be returned if
  261. pathLength is too small.  parts[0] should contain the deepest pathName element,
  262. and parts[nParts - 1] should contain the name of the first pathName element beneath
  263. the root. 
  264. */
  265. /*
  266. Check the equality of two packed paths.
  267. */
  268. /*
  269. OCEValidPackedPathName checks that the packed PathName is internally consistent.
  270. Returns true if it's ok.
  271. */
  272. /**** DirDiscriminator ****/
  273. typedef SOMLargeStruct            DirDiscriminator;            /* Derived from a struct of 8 bytes in size */
  274.  
  275. /* Copies the value of disc1 to disc2. */
  276. /* Check the equality of two DirDiscriminators. */
  277. /*
  278. This structure is called RLI because it really contains all the info you
  279. need to locate a record within the entire name space.  It contains four fields.
  280. The first two are the name of the catalog and a catalog discriminator.  These
  281. two fields are used to indicate to which catalog a given record belongs.  The
  282. discriminator is used to distinguish between two different catalogs that have
  283. the same name.
  284.  
  285. The other two fields in the RLI structure are used to indicate a particular
  286. catalog node within the catalog specified by the directoryName and
  287. discriminator fields.  These fields are exactly analagous to the dirID and
  288. pathname used in HFS.  It is possible to specify a dNode just by dNodeNumber
  289. (pathname is nil), or just by pathname (dNodeNumber is set to kNULLDNodeNumber),
  290. or by a combination of the two.  The latter is called a 'partial pathname', and
  291. while it is valid in the Catalog Manager API, it is not supported by ADAP
  292. catalogs in Release 1.
  293.  
  294. Note that the path parameter does not include the catalog name, but holds
  295. the names of all the nodes on the path to the desired catalog node, starting
  296. with the catalog node and working its way up the tree.
  297. */
  298. /**** RLI ****/
  299. typedef SOMLargeStruct            DirectoryName;                /* Derived from a struct of 36 bytes in size */
  300.  
  301. typedef OpaquePtr                DirectoryNamePtr;            /* Substituted OpaquePtr for ``DirectoryName*'' */
  302.  
  303. /* Catalog node number */
  304. typedef unsigned long            DNodeNum;
  305.  
  306. typedef SOMLargeStruct            RLI;                        /* Derived from a struct of 20 bytes in size */
  307.  
  308. typedef OpaquePtr                RLIPtr;                        /* Substituted OpaquePtr for ``RLI*'' */
  309.  
  310. /*
  311. Create a new RLI from the catalog name, discriminator, DNode number, and
  312. PackedPathName.  You must allocate the storage for the RLI and pass in a pointer
  313. to it.
  314. */
  315. /*
  316. Duplicate the contents of rli1 to rli2.  No errors are returned. This
  317. simply copies the pointers to the catalog name and path, wiping out any pointer
  318. that you might have had in there.
  319. */
  320. /*
  321. Copy the contents of rli1 to rli2.  rli2 must already contain
  322. pointers to structures large enough to hold copies of the corresponding
  323. fields from rli1.  A memFull error will be returned if that is not the case.
  324. So if you allocate a brand new empty destination, you must at least set up
  325. its length fields.
  326. */
  327. /*
  328. Check the equality of two RLIs.  This will take into account differences
  329. in the case and diacriticals of the directoryName and the PathName.
  330. NOTE THAT THIS WILL FAIL IF rli1 CONTAINS A DNODENUMBER AND A NIL PATHNAME,
  331. AND rli2 CONTAINS kNULLDNodeNumber AND A NON-NIL PATHNAME.  IN OTHER WORDS,
  332. THE TWO rlis MUST BE OF THE SAME FORM TO CHECK FOR EQUALITY.
  333. The one exception is that if the pathname is nil, a dNodeNumber of zero and
  334. kRootDNodeNumber will be treated as equal.
  335. */
  336. /*
  337. Check the validity of an RLI.  This checks that the catalog name length
  338. is within bounds, and the packed pathname (if specified) is valid.
  339. */
  340. /**** PackedRLI ****/
  341. /*
  342. struct PackedRLI is a maximum-sized structure.  Allocate one of
  343. these and it will hold any valid packed pathname.
  344. */
  345. typedef SOMLargeStruct            PackedRLI;                    /* Derived from a struct of 1298 bytes in size */
  346.  
  347. /*
  348. struct ProtoPackedRLI is a minimum-sized structure.  Use this
  349. for a variable-length packed RLI.
  350. */
  351. typedef SOMTwoByteStruct        ProtoPackedRLI;                /* Derived from a struct of 2 bytes in size */
  352.  
  353. typedef OpaquePtr                PackedRLIPtr;                /* Substituted OpaquePtr for ``PackedRLI*'' */
  354.  
  355. typedef OpaquePtr                ProtoPackedRLIPtr;            /* Substituted OpaquePtr for ``ProtoPackedRLI*'' */
  356.  
  357. /*
  358. Copy the contents of prli1 to prli2.  prli2Length is the size of prli2, and must
  359. be large enough to hold a copy of prli1.  A memFull error will be returned if that
  360. is not the case.
  361. */
  362. /*
  363. OCEUnpackRLI breaks apart the prli into its components, writing pointers into
  364. the rli structure.  NOTE THAT THE UNPACKED STRUCT CONTAINS POINTERS INTO THE
  365. PACKED STRUCT - DON'T DELETE OR REUSE THE PACKED STRUCT UNTIL YOU ARE FINISHED
  366. WITH THE UNPACKED STRUCT AS WELL
  367. */
  368. /*
  369. OCEPackedRLISize computes the number of bytes of memory needed to hold a
  370. PackedRLI manufactured from an RLI.  This length
  371. includes the length of the length field of PackedRLI, so it
  372. is safe to do a NewPtr (OCEPackedRLISize(...)).
  373. */
  374. /*
  375. OCEPackRLI packs the RLI into the storage provided as 'prli'.  prli must be
  376. large enough to hold the packed RLI.  A memFull error will be returned if
  377. prliLength is too small.
  378. */
  379. /*
  380. OCEPackedRLIPartsSize computes the number of bytes of memory needed to hold a
  381. PackedRLI manufactured from the parts of an RLI.  This length
  382. includes the length of the length field of PackedRLI, so it
  383. is safe to do a NewPtr (OCEPackedRLIPartsSize(...)).
  384. */
  385. /*
  386. OCEPackRLIParts packs the parts of an RLI into the storage provided as 'prli'.
  387. prli must be large enough to hold the packed RLI.  A memFull error will be returned
  388. if prliLength is too small.
  389. */
  390. /*
  391. Check the equality of two packed prlis.
  392. */
  393. /*
  394. Check the validity of a packed RLI.  This checks that the catalog name length
  395. is within bounds, and the packed pathname (if specified) is valid.
  396. */
  397. /*
  398. If this packed RLI describes a Personal Catalog, this call will return a pointer
  399. to an alias record that can be used to find the actual file.  Otherwise, it returns nil.
  400. */
  401. /*
  402. This call returns a pointer to a packed RLI that represents the "Catalogs" icon, or
  403. the root of all catalogs.  It is used in the CollabPack.
  404. */
  405. /**** LocalRecordID ****/
  406. typedef SOMLargeStruct            LocalRecordID;                /* Derived from a struct of 16 bytes in size */
  407.  
  408. typedef OpaquePtr                LocalRecordIDPtr;            /* Substituted OpaquePtr for ``LocalRecordID*'' */
  409.  
  410. /* Create a LocalRecordID from a name, type, and CreationID */
  411. /*
  412. Copy LocalRecordID lRID1 to LocalRecordID lRID2.  lRID2 must already contain
  413. pointers to RString structures large enough to hold copies of the corresponding
  414. fields from lRID1.  A memFull error will be returned if that is not the case.
  415. So if you allocate a brand new empty destination, you must at least set up
  416. its length field.
  417. */
  418. /*
  419. Check the equality of two local RIDs.
  420. */
  421. /**** ShortRecordID ****/
  422. typedef SOMLargeStruct            ShortRecordID;                /* Derived from a struct of 12 bytes in size */
  423.  
  424. typedef OpaquePtr                ShortRecordIDPtr;            /* Substituted OpaquePtr for ``ShortRecordID*'' */
  425.  
  426. /* Create a ShortRecordID from an RLI struct and a CreationID */
  427. /*
  428. Copy ShortRecordID sRID1 to ShortRecordID sRID2.  sRID2 must already contain
  429. pointers to structures large enough to hold copies of the corresponding
  430. fields from sRID1.  A memFull error will be returned if that is not the case.
  431. So if you allocate a brand new empty destination, you must at least set up
  432. its length fields.
  433. */
  434. /*
  435. Check the equality of two short RIDs.
  436. */
  437. /**** RecordID ****/
  438. typedef SOMLargeStruct            RecordID;                    /* Derived from a struct of 20 bytes in size */
  439.  
  440. typedef OpaquePtr                RecordIDPtr;                /* Substituted OpaquePtr for ``RecordID*'' */
  441.  
  442. /*
  443.     Create a RecordID from a packed RLI struct and a LocalRecordID.
  444. This doesn't allocate any new space; the RecordID points to the same
  445. packed RLI struct and the same name and type RStrings. 
  446. */
  447. /*
  448. Copy RecordID RID1 to RecordID RID2.  RID2 must already contain
  449. pointers to structures large enough to hold copies of the corresponding
  450. fields from lRID1.  A memFull error will be returned if that is not the case.
  451. So if you allocate a brand new empty destination, you must at least set up
  452. its length fields.
  453. */
  454. /*    Check the equality of two RIDs. */
  455. /**** PackedRecordID ****/
  456. /*
  457. struct PackedRecordID is a maximum-sized structure.  Allocate one of
  458. these and it will hold any valid packed RecordID.
  459. */
  460. typedef SOMLargeStruct            PackedRecordID;                /* Derived from a struct of 1826 bytes in size */
  461.  
  462. /*
  463. struct ProtoPackedRecordID is a minimum-sized structure.  Use this
  464. for a variable-length packed RecordID.
  465. */
  466. typedef SOMTwoByteStruct        ProtoPackedRecordID;        /* Derived from a struct of 2 bytes in size */
  467.  
  468. typedef OpaquePtr                PackedRecordIDPtr;            /* Substituted OpaquePtr for ``PackedRecordID*'' */
  469.  
  470. typedef OpaquePtr                ProtoPackedRecordIDPtr;        /* Substituted OpaquePtr for ``ProtoPackedRecordID*'' */
  471.  
  472. /*
  473. Copy PackedRecordID pRID1 to PackedRecordID pRID2.  pRID2 must already contain
  474. pointers to structures large enough to hold copies of the corresponding
  475. fields from pRID1.  A memFull error will be returned if that is not the case.
  476. pRID2Length is the number of bytes that can be put into pRID2, not counting the
  477. packed RecordID header.
  478. */
  479. /*
  480. Create a RecordID from a PackedRecordID.
  481. NOTE THAT THE UNPACKED STRUCT CONTAINS POINTERS INTO THE PACKED STRUCT - DON'T DELETE
  482. OR REUSE THE PACKED STRUCT UNTIL YOU ARE FINISHED WITH THE UNPACKED STRUCT AS WELL
  483. */
  484. /*
  485. Create a PackedRecordID from a RecordID.  pRID must be large enough to contain
  486. the packed RecordID.  A memFull error will be returned if that is not the case.
  487. packedRecordIDLength is the number of bytes that can be put into pRID, not
  488. counting the header.
  489. */
  490. /*
  491. Compute the number of bytes of memory needed to hold a RecordID when packed. This
  492. length includes the length of the length field of PackedRecordID, so it
  493. is safe to do a NewPtr (OCEPackedRecordIDSize(...)).
  494. */
  495. /*
  496. Check the equality of two packed RIDs.
  497. */
  498. /* OCEValidPackedRecordID checks the validity of a packed record ID. */
  499. /**** DSSpec ****/
  500. typedef SOMLargeStruct            DSSpec;                        /* Derived from a struct of 14 bytes in size */
  501.  
  502. typedef OpaquePtr                DSSpecPtr;                    /* Substituted OpaquePtr for ``DSSpec*'' */
  503.  
  504. /*
  505. struct PackedDSSpec is NOT a maximum-sized structure.  Allocate one of
  506. these and it will hold any valid packed RecordID, but not necessarily any additional
  507. data.
  508. */
  509. typedef SOMLargeStruct            PackedDSSpec;                /* Derived from a struct of 1834 bytes in size */
  510.  
  511. typedef OpaquePtr                PackedDSSpecPtr;            /* Substituted OpaquePtr for ``PackedDSSpec*'' */
  512.  
  513. typedef OpaquePtr                PackedDSSpecHandle;            /* Substituted OpaquePtr for ``PackedDSSpecPtr*'' */
  514.  
  515. /*
  516. struct ProtoPackedDSSpec is a minimum-sized structure.  Use this
  517. for a variable-length packed DSSpec.
  518. */
  519. typedef SOMTwoByteStruct        ProtoPackedDSSpec;            /* Derived from a struct of 2 bytes in size */
  520.  
  521. typedef OpaquePtr                ProtoPackedDSSpecPtr;        /* Substituted OpaquePtr for ``ProtoPackedDSSpec*'' */
  522.  
  523. /*
  524. Copy PackedDSSpec pdss1 to PackedDSSpec pdss2.  pdss2 must already contain
  525. pointers to structures large enough to hold copies of the corresponding
  526. fields from pdss1.  A memFull error will be returned if that is not the case.
  527. pdss2Length is the number of bytes that can be put into pdss2, not counting the
  528. packed DSSpec header.
  529. */
  530. /*
  531. Create a DSSpec from a PackedDSSpec.
  532. NOTE THAT THE UNPACKED STRUCT CONTAINS POINTERS INTO THE PACKED STRUCT - DON'T DELETE
  533. OR REUSE THE PACKED STRUCT UNTIL YOU ARE FINISHED WITH THE UNPACKED STRUCT AS WELL.
  534. A pointer to the extension is returned in dss->extensionValue, and the length of that
  535. extension is returned in dss->extensionSize.  If there is no extension, dss->extensionValue will
  536. be set to nil.  This routine will unpack the RecordID (if any) into rid, unpack the rest
  537. into dss, and set dss->entitySpecifier to rid.
  538. */
  539. /*
  540. Create a PackedDSSpec from a DSSpec.  pdss must be large enough to
  541. contain the packed RecordID and any extension.  A memFull error will be returned if that
  542. is not the case.  pdssLength is the number of bytes that can be put into pdss,
  543. not counting the header.
  544. */
  545. /*
  546. Compute the number of bytes of memory needed to hold a DSSpec when packed. This
  547. length includes the length of the length field of PackedDSSpec, so it
  548. is safe to do a NewPtr (OCEPackedDSSpecSize(...)).
  549. */
  550. /*
  551.     Check the equality of two DSSpecs.  This compares all fields, even the
  552. extension (unless extensionSize == 0).  The extensions are compared in a case-insensitive and
  553. diacrit-insensitive manner. 
  554. */
  555. /*
  556.     Check the equality of two PackedDSSpecs.  This compares all fields, even the
  557. extension (unless extensionSize == 0).  The extensions are compared in a case-insensitive and
  558. diacrit-insensitive manner. 
  559. */
  560. /*
  561. Check the validity of a PackedDSSpec.  If extensionType is
  562. 'entn', pdss must contain a valid entitySpecifier.  For all other extensionTypes, a nil
  563. entitySpecifier is valid, but if non-nil, it will be checked for validity.  No check
  564. is made on the extension.
  565. */
  566. /*
  567. Return info about a DSSpec.  This routine does not check validity.  If the
  568. DSSpec has no extension, we determine whether it represents the root of all
  569. catalogs, a single catalog, a DNode, or a Record.  Else it is invalid.
  570. If the DSSpec has an extension, we simply return the extension type.
  571. */
  572. /* OCEGetExtensionType returns the extensionType imbedded in the PackedDSSpec. */
  573. /*
  574. OCEStreamPackedDSSpec streams (flattens) a catalog object a little at a time by
  575. calling the DSSpecStreamer routine that you provide.
  576. */
  577. typedef OpaquePtr DSSpecStreamerProcPtr;
  578. typedef OpaquePtr DSSpecStreamerUPP;
  579. typedef DSSpecStreamerUPP        DSSpecStreamer;
  580.  
  581. /**** AttributeType ****/
  582. /*
  583. For the record, an AttributeType is an RString with a smaller maximum size.
  584. I don't just typedef it to an RString, because I want the definition of the AttributeType
  585. struct to contain the max length, because I need to include it in the Attribute struct
  586. below.  But it should be possible to typecast any AttributeType to an RString and use
  587. all the RString utilities on it.
  588. */
  589. typedef SOMLargeStruct            AttributeType;                /* Derived from a struct of 36 bytes in size */
  590.  
  591. typedef OpaquePtr                AttributeTypePtr;            /* Substituted OpaquePtr for ``AttributeType*'' */
  592.  
  593. /* Miscellaneous defines:  (these cannot be made into enums) */
  594. /**** AttributeValue ****/
  595. /* same class as is used in AppleEvents */
  596. typedef DescType                AttributeTag;
  597.  
  598. typedef SOMLargeStruct            AttributeValue;                /* Derived from a struct of 12 bytes in size */
  599.  
  600. typedef OpaquePtr                AttributeValuePtr;            /* Substituted OpaquePtr for ``AttributeValue*'' */
  601.  
  602. /**** Attribute ****/
  603. typedef SOMLargeStruct            Attribute;                    /* Derived from a struct of 56 bytes in size */
  604.  
  605. typedef OpaquePtr                AttributePtr;                /* Substituted OpaquePtr for ``Attribute*'' */
  606.  
  607. /*
  608. ***************************************************************************************
  609.    PLEASE NOTE! ROUTINES HAVE MOVED TO THIS HEADER!
  610.  
  611.    OCESizePackedRecipient, OCEPackRecipient, OCEUnpackRecipient, OCEStreamRecipient,
  612.    OCEGetRecipientType, and OCESetRecipientType have moved to the OCE header file.
  613.    The OCEMessaging header includes the OCE header, so no changes to your code are
  614.    required.
  615.  
  616. ***************************************************************************************
  617. */
  618. typedef DSSpec                    OCERecipient;
  619.  
  620. /*
  621. Compute the space that a OCERecipient would take if it were in packed
  622. form.  [Note: does NOT even pad extensionSize, so you may get an odd #back out]
  623. Safe to pass dereferenced handle(s).
  624. */
  625. /*
  626. Take an OCERecipient (scatter) and (gather) stream into the specified
  627. buffer.  It is assumed that there is sufficient space in the buffer (that is
  628. OCESizePackedRecipient).  Safe to pass dereferenced handle(s).
  629. */
  630. /*
  631. Take a packed OCERecipient and cast a the OCERecipient frame over it. Returns
  632. amBadDestId if it doesn't look like an OCERecipient. Safe to pass dereferenced
  633. handle(s).
  634. */
  635. /*
  636. Take an OCERecipient (scatter) and (gather) stream using the specified
  637. function.  Safe to pass dereferenced handle(s).  If streamer function returns
  638. OCEError OCEStreamRecipient stops execution and passes the error back to the caller
  639. */
  640. typedef OpaquePtr OCERecipientStreamerProcPtr;
  641. typedef OpaquePtr OCERecipientStreamerUPP;
  642. typedef OCERecipientStreamerUPP OCERecipientStreamer;
  643.  
  644. /* Get the OCERecipient's extensionType. Safe to pass dereferenced handle(s).*/
  645. /*
  646. Set the OCERecipient's extensionType in the specified cid.  (Note: we do NOT
  647. check for a nil pointer).  If the extensionType is 'entn', the cid is assumed
  648. to be "valid" and is not touched.  Note: to properly handle non 'entn''s this
  649. routine must and will zero the high long (source) of the cid! Safe to pass
  650. dereferenced handle(s).
  651. */
  652. /*
  653. ***************************************************************************************
  654.    PLEASE NOTE! ROUTINES HAVE MOVED TO THIS HEADER!
  655.  
  656.    OCEGetAccessControlDSSpec and its corresponding data type and constants have
  657.    moved to the OCE header from OCEAuthDir. The OCEAuthDir header includes the OCE
  658.    header, so no changes to your code are required.
  659.    
  660. ***************************************************************************************
  661. */
  662. /* access categories bit numbers */
  663. /* Values of CategoryMask */
  664. typedef unsigned long            CategoryMask;
  665.  
  666. /*
  667. pass kThisRecordOwnerMask, kFriendsMask, kAuthenticatedInDNodeMask, kAuthenticatedInDirectoryMask,
  668. kGuestMask, or kMeMask to this routine, and it will return a pointer to a
  669. DSSpec that can be used in the Get or Set Access Controls calls.
  670. */
  671. #endif
  672.  
  673. #endif /* __SOMIDL__ */
  674.  
  675. #endif /* __OCE_IDL__ */
  676.  
  677.